home *** CD-ROM | disk | FTP | other *** search
/ Aminet 6 / Aminet 6 - June 1995.iso / Aminet / util / blank / bserver_v14.lha / BServer_v1.4 / Sources.lha / Sources / include / client.h < prev    next >
Encoding:
C/C++ Source or Header  |  1995-03-23  |  8.0 KB  |  315 lines
  1. /*
  2.  * Client.h v1.2
  3.  * Copyright © 1994 by Stefano Reksten of 3AM - The Three Amigos!!!
  4.  * All rights reserved.
  5.  *
  6.  * This file and client.lib are needed to build a client blanker.
  7.  *
  8.  * What's to do:
  9.  *
  10.  * When blanking is needed, BServer will choose a client and launch it.
  11.  * So when you are launched, it's supposed you will blank the screen!
  12.  *
  13.  * OpenCommunication() will return you a DisplayIDInformation structure
  14.  * (see below). In this structure you'll find the user's preferred display
  15.  * id, overscan dimensions, etc.
  16.  *
  17.  * If anything goes wrong, SendClientMsg( ACTION_FAILED ) will tell BServer
  18.  * to run another client from its list (or to use its builtin blanker).
  19.  *
  20.  * When any input activity takes place, BServer will issue you a command
  21.  * that will be hopefully COMMAND_QUIT. So long, you aren't needed anymore.
  22.  * Do your cleanup, CloseCommunication( <your DisplayIDInformation> ) and
  23.  * exit.
  24.  *
  25.  * Have fun! :-)
  26.  *
  27.  *
  28.  * Here's the complete documentation of the function you can use to
  29.  * interact with your server. (Functions that are internal only, like
  30.  * AllocClientMessage, are not documented.)
  31.  * 
  32.  * 
  33.  * NAME
  34.  *   OpenCommunication
  35.  *
  36.  * SYNOPSIS
  37.  *   dinfo = OpenCommunication()
  38.  *
  39.  *   struct DisplayIDInformation * = OpenCommunication()
  40.  *
  41.  * FUNCTION
  42.  *   Opens a connection between your blanker (client) and the server.
  43.  *
  44.  * RESULTS
  45.  *   A DisplayIDInformation if communication was opened, NULL otherwise.
  46.  *
  47.  * SEE ALSO
  48.  *   CloseCommunication()
  49.  *
  50.  *
  51.  *
  52.  *
  53.  * NAME
  54.  *   CloseCommunication
  55.  *
  56.  * SYNOPSIS
  57.  *   CloseCommunication( dinfo )
  58.  *
  59.  *   void CloseCommunication( struct DisplayIDInformation * )
  60.  *
  61.  * FUNCTION
  62.  *   Closes communication between your client and the server. Frees the
  63.  *   structure returned by OpenCommunication.
  64.  *
  65.  * SEE ALSO
  66.  *   OpenCommunication()
  67.  *
  68.  *
  69.  *
  70.  *
  71.  * NAME
  72.  *   SendClientMsg
  73.  *
  74.  * SYNOPSIS
  75.  *   success = SendClientMsg( action )
  76.  *
  77.  *   BOOL = SendClientMsg( ULONG )
  78.  *
  79.  * FUNCTION
  80.  *   Sends a message to the server (waiting reply). Of course, your
  81.  *   client should already have opened a communication with the server.
  82.  *
  83.  * INPUTS
  84.  *   action: an UBYTE describing the action you're performing. This may be:
  85.  *
  86.  *          o ACTION_FAILED  (You couldn't start your blanking actions,
  87.  *                           so you are telling the server to ask
  88.  *                           another blanker.)
  89.  *
  90.  * RETURNS
  91.  *   TRUE if message was received, FALSE otherwise.
  92.  *
  93.  * SEE ALSO
  94.  *   OpenCommunication()
  95.  *
  96.  *
  97.  *
  98.  *
  99.  * NAME
  100.  *   GetServerCommand, WaitServerCommand
  101.  *
  102.  * SYNOPSIS
  103.  *   command = GetServerCommand()
  104.  *   command = WaitServerCommand()
  105.  *
  106.  *   UBYTE = GetServerCommand()
  107.  *   UBYTE = WaitServerCommand()
  108.  *
  109.  * FUNCTION
  110.  *   It returns the command sent by the server. The difference between
  111.  *   the two functions is that GetServerCommand checks the communication
  112.  *   port searching for any message coming from the server, while
  113.  *   WaitServerCommand will make your program wait until a command
  114.  *   (different from COMMAND_IDLE) is received.
  115.  *   The server may send you these commands:
  116.  *   o COMMAND_IDLE:    the CommunicationPort is empty. This one can be
  117.  *                      obtained only with GetServerCommand.
  118.  *   o COMMAND_QUIT:    the server is asking you to quit.
  119.  *   Note that GetServerCommand POLLS the port so don't use it out of any
  120.  *   rendering (or something else) cycle. Use WaitServerCommand instead.
  121.  *
  122.  * SEE ALSO
  123.  *   any client's source
  124.  *
  125.  *
  126.  *
  127.  * Here are some macros that you can use for quicker programming.
  128.  *
  129.  *
  130.  * NAME
  131.  *   DISPLAYID
  132.  *
  133.  * SYNOPSIS
  134.  *   DisplayID = DISPLAYID( dinfo )
  135.  *
  136.  *   ULONG = DISPLAYID( struct DisplayIDInformation * )
  137.  *
  138.  * MACRO
  139.  *   This macro returns you an ULONG containing the screen mode choosen
  140.  *   by the user for a client.
  141.  *
  142.  *
  143.  *
  144.  *
  145.  * NAME
  146.  *   FILTEROUT
  147.  *
  148.  * SYNOPSIS
  149.  *   newDisplayID = FILTEROUT( oldDisplayID, flags_to_remove )
  150.  *
  151.  *   ULONG = FILTEROUT( ULONG, ULONG )
  152.  *
  153.  * MACRO
  154.  *  This macro removes all the unwanted flags from a DisplayID, e.g.:
  155.  *  you are told to blank; the server sent you also the preferred
  156.  *  screenmode (stored in dinfo). You want to filter SUPERHIRES mode
  157.  *  and LACE flag but want a hires screen. You could pass as value
  158.  *  for SA_DisplayID this value:
  159.  *  FILTEROUT( DISPLAYID(dinfo) | HIRES, SUPERHIRES|LACE )
  160.  *
  161.  * SEE ALSO
  162.  *   GetServerCommand(), WaitServerCommand()
  163.  *
  164.  *
  165.  *
  166.  *
  167.  * NAME
  168.  *   GETSTANDARDRECT   
  169.  *   GETMAXOSCANRECT
  170.  *   GETVIDEOOSCANRECT
  171.  *   GETTXTOSCANRECT
  172.  *   GETSTDOSCANRECT
  173.  *
  174.  * SYNOPSIS
  175.  *   rectangle = GET...RECT( struct DisplayIDInformation * )
  176.  *
  177.  *   struct Rectangle * = GET...RECT( struct DisplayIDInformation * )   
  178.  *
  179.  * MACRO
  180.  *   These macro return the address of a Rectangle structure containing
  181.  *   a certain overscan value. (As ever, the DisplayIDInformation
  182.  *   structure was allocated by your server)
  183.  *
  184.  *
  185.  *
  186.  *
  187.  * NAME
  188.  *   RECTANGLEWIDTH
  189.  *   RECTANGLEHEIGHT
  190.  *
  191.  * SYNOPSIS
  192.  *  width = RECTANGLEWIDTH( rect )
  193.  *  height = RECTANGLEHEIGHT( rect )
  194.  *
  195.  *  UWORD = RECTANGLEWIDTH( struct Rectangle * )
  196.  *  UWORD = RECTANGLEHEIGHT( struct Rectangle * )
  197.  *
  198.  * MACRO
  199.  *  This macro returns the current width/height for a screen from a
  200.  *  Rectangle structure.
  201.  *
  202.  *
  203.  *
  204.  * Here are two functions you can use also for smaller sources:
  205.  *
  206.  *
  207.  * NAME
  208.  *  SpritesOff()
  209.  *
  210.  * SYNOPSIS
  211.  *  SpritesOff()
  212.  *
  213.  * FUNCTION
  214.  *  Disables sprite DMA, removes sprite from screen.
  215.  *  Remember that performing a ScreenToFront action (when doublebuffering)
  216.  *  or similar will activate sprite DMA again.
  217.  *
  218.  * SEE ALSO
  219.  *  SpritesOn(), Balls.c, any other client's source
  220.  *
  221.  * BUGS
  222.  *  Well sprites should remain deactivated...
  223.  *
  224.  *
  225.  *
  226.  * NAME
  227.  *  SpritesOn()
  228.  *
  229.  * SYNOPSIS
  230.  *  SpritesOn()
  231.  *
  232.  * FUNCTION
  233.  *  Enables sprite DMA.
  234.  *
  235.  * SEE ALSO
  236.  *  SpritesOff()
  237.  *
  238.  *
  239.  *
  240.  * NAME
  241.  *  CheckAA()
  242.  *
  243.  * SYNOPSIS
  244.  *  aa_chipset = CheckAA()
  245.  *
  246.  *  BOOL = CheckAA( void )
  247.  *
  248.  * FUNCTION
  249.  *  Tells wether AA chipset is installed or not, and if you can use it
  250.  *  (that is, if you have kickstart 3.0+ installed). If this function
  251.  *  returns FALSE, you have to fall back to 2.0, or to quit. As a general
  252.  *  behaviour, a client should fall back to ECS.
  253.  */
  254.  
  255. #ifndef GRAPHICS_DISPLAYINFO_H
  256. #include <graphics/displayinfo.h>
  257. #endif
  258.  
  259. #ifndef CLIENT_H
  260. #define CLIENT_H
  261.  
  262. /* Client actions  - what the client can say to the server */
  263.  
  264. #define ACTION_FAILED      3
  265.  
  266. /* Server commands - what the server can say to the client */
  267.  
  268. #define COMMAND_IDLE        0
  269. #define COMMAND_QUIT        1
  270.  
  271. /*=====================================================*/
  272. /*=== DisplayIDInformation ============================*/
  273. /*=====================================================*/
  274.  
  275. struct DisplayIDInformation
  276.     {
  277.     struct DisplayInfo   di_DisplayInfo;
  278.     struct DimensionInfo di_DimensionInfo;
  279.     struct MonitorInfo   di_MonitorInfo;
  280.     UBYTE di_Brightness;
  281.     };
  282.  
  283. /* These information should be enough. :-) */
  284.  
  285. #define FREEDISPLAYIDINFO(dinf) FreeServerData(dinf)
  286. #define DISPLAYID(dinf)         dinf->di_DisplayInfo.Header.DisplayID
  287. #define FILTEROUT(id,flags)     ((id) & ~(flags))
  288. #define GETSTANDARDRECT(dinf)   &(dinf->di_DimensionInfo.Nominal)
  289. #define GETMAXOSCANRECT(dinf)   &(dinf->di_DimensionInfo.MaxOScan)
  290. #define GETVIDEOOSCANRECT(dinf) &(dinf->di_DimensionInfo.VideoOScan)
  291. #define GETTXTOSCANRECT(dinf)   &(dinf->di_DimensionInfo.TxtOScan)
  292. #define GETSTDOSCANRECT(dinf)   &(dinf->di_DimensionInfo.StdOScan)
  293. #define GETBRIGHTNESS(dinf)     (dinf->di_Brightness)
  294.  
  295. #define RECTANGLEWIDTH(r)    ((r)->MaxX - (r)->MinX + 1)
  296. #define RECTANGLEHEIGHT(r)    ((r)->MaxY - (r)->MinY + 1)
  297.  
  298. #define STILL_BLANKING (GetServerCommand()==COMMAND_IDLE)
  299.  
  300. /* Protypes for the functions you need to communicate with BServer */
  301.  
  302. BOOL  __asm __saveds SendClientMsg( register __d0 ULONG );
  303. ULONG __asm __saveds GetServerCommand( void );
  304. ULONG __asm __saveds WaitServerCommand( void );
  305. struct DisplayIDInformation *__asm __saveds OpenCommunication( void );
  306. void  __asm __saveds CloseCommunication( register __a1 struct DisplayIDInformation * );
  307.  
  308. /* Feel free to use these functions */
  309.  
  310. void __asm __saveds SpritesOff( void );
  311. void __asm __saveds SpritesOn( void );
  312. BOOL __asm __saveds CheckAA( void );
  313.  
  314. #endif
  315.